8bitfiles.net/archives/archives.tar/archives/compuserve-file-archive/04 geoProgramming/G128TE.REF

Text File | 2019-04-13 | 14.1 KB | 374 lines

geos tECHNICAL rEFERENCE nOTES
dECEMBER, 1987

tHIS DOCUMENT PROVIDES SOME PRELIMINARY INFORMATION ABOUT THE DIFFERENCES
BETWEEN c64 geos AND c128 geos. iT IS NOT INTENDED TO BE COMPREHENSIVE;

cOMPATIBILITY WITH c64 geos SOFTWARE
------------------------------------
mOST c64 geos SOFTWARE WILL RUN UNDER THE c128 geos IN 40 COLUMN MODE.

aLL DATA FILES, SCRAPS, FONTS, & PRINTER DRIVERS ARE IDENTICAL UNDER
c64 AND c128 geos.

iNPUT DRIVERS ARE LOCATED AT DIFFERENT ADDRESSES IN THE TWO MACHINES, AND
HENCE ARE INCOMPATIBLE.  wE HAVE ADDED A NEW FILE TYPE, input128, FOR c128
INPUT DRIVERS.

aS THE DESKtOP IS HEAVILY TIED INTO EACH os, WE'VE DECIDED TO GIVE THE 128
IT'S OWN DESKTOP FILENAME, "128 desktop", SO AS TO AVOID CONFUSION WITH THE
64'S "desk top" FILE.  (tHE DESKtOP IS OF FILE TYPE "system", AND CAN'T BE
RENAMED BY THE USER).


128 fLAGS FOR aPPLICATIONS & dESK aCCESSORIES
---------------------------------------------
iN ORDER FOR THE 128 desktop & OTHER APPLICATIONS TO KNOW WHAT FILES RUN IN
WHAT MODE, WE'VE ADOPTED A STANDARD THAT SHOULD BE USED ON all APPLICATIONS,
DESK ACCESSORIES, & AUTO-EXECUTION PROGRAMS.  tHIS FLAG IS LOCATED IN THE
HEADER BLOCK OF EACH OF THESE PROGRAMS.  sINCE PERMANENT FILE NAMES ARE ONLY
16 BYTES LONG, WE HAVE LEFT OVER 4 BYTES THAT HAVE BEEN UNUSED TILL NOW, BUT
WE'VE CONSTANTLY BEEN SETTING THEM TO ALL 0'S.  tHE LAST OF THESE BYTES
(SEE off128flags) NOW HAS MEANING TO THE 128 os & dESKtOP:

b7 b6
 0  0  RUNS UNDER 128 geos, BUT IN 40 COLUMN MODE ONLY
 0  1  RUNS UNDER 128 geos IN 40 AND 80 COLUMN MODES
 1  0  does not run UNDER 128 geos (DESKtOP WILL DISPLAY DIALOG BOX)
 1  1  RUNS UNDER 128 geos IN 80 COLUMN MODE ONLY

bITS 5 THROUGH 0 ARE UNUSED AND SHOULD BE 0. tHE 128 geos ROUTINES lDaPPLIC
AND lDdESKaCC WILL RETURN THE ERROR #incompatible IF THESE FLAGS IN THE HEADER
BLOCK DO NOT ALLOW RUNNING IN THE CURRENT MODE.


cONVERTING 64 geos SOFTWARE TO RUN ON THE c128
----------------------------------------------
fIRST, YOU NEED TO DECIDE WHETHER YOUR SOFTWARE IS SIMPLY GOING TO BE ABLE TO
RUN IN 40 COL. MODE, OR WHETHER IT IS TO RUN IN 40/80 COLUMN ON THE 128 ONLY.

40 COL. MODE ONLY ON 128:

1) cHANCES ARE QUITE GOOD YOUR SOFTWARE ALREADY DOES.

2) iF IT DOESN'T, IT'S PROBABLY BECUASE YOU ACCESS basic -- THE 128 HAS A
DIFFERENT basic, SO YOU'LL NEED TO RE-WRITE THAT SECTION OF CODE TO FIRST SEE
WHICH os YOU'RE RUNNING UNDER, & THEN USE THE APPROPRIATE basic VARIABLES &
JUMP ENTRIES.

40/80 COL. ON THE c128 ONLY:

1) sET THE 128 FLAG AS MENTIONED ABOVE IN THE SAVE FILE TO $40

2) iN 80 COLUMN MODE, YOU'LL NEED TO WIDEN YOUR MENUS TO ACCOMODATE THE WIDER
SYSTEM FONT.  wE TYPICALLY STUFF THESE "RIGHT EDGE" VALUES INTO THE MENU
STRUCTURE ITSELF BASED ON THE CURRENT GRAPHICSmODE
($80 IS 80 COLUMN, $00 IS 40)

3) mOST OF THE GRAPHIC CHANGES YOU'LL NEED TO MAKE CAN BE ACCOMPLISHED BY
SETTING THE HIGH BIT OF EVERY x POSITION OR WIDTH THAT YOU PASS TO THE
OPERATING SYSTEM. tHE 128 geos WILL IGNORE THIS BIT IF IN 40 COLUMN MODE,
AND DOUBLE THE VALUE IF IN 80 COLUMN MODE, THUS AUTOMATICALLY RETAINING THE
SAME SIZED IMAGE ON THE SCREEN. hENCE, 50+$8000 IS 50 PIXELS IN 40 COLUMN
MODE AND 100 PIXELS IN 80 COLUMN MODE.

4) iF YOU'RE WRITING AN APPLICATION, ADD A "SWITCH 40/80" OPTION UNDER THE
GEOS MENU.  tHE ACTION FOR THIS SHOULD BE TO eor GRAPHICSmODE WITH $80,
STORE IT BACK, AND CALL THE ROUTINE sETnEWmODE. yOU'LL THEN NEED TO REDRAW THE
SCREEN, NOW IN THE NEW GRAPHICS MODE.

5) nEARLY ALL X POSITIONS PASSED TO THE c128 geos CAN HAVE THE HIGH BIT SET
CAUSING THE POSITION TO AUTOMATICALLY BE DOUBLED IN 80 COLUMN MODE.  iT HAS
BEEN NOTED THAT THIS ALWAYS RESULTS IN THE LOW BIT OF THE RESULTING WORD BEING
A 0.  tHIS CAN MAKE LIFE DIFFICULT, IF YOU DESIRE TO FILL A PATTERN TO THE
RIGHT EDGE OF THE SCREEN, FOR INSTANCE.  tO SOLVE THIS PROBLEM, i'VE MODIFIED
THE NORMALIZATION ROUTINE:  tHE 15TH BIT OF THE WORD CONTINUES TO BE THE SAME
"DOUBLE ME IF 80 COL." FLAG, BUT THE 14TH BIT NOW HAS SIGNIFICANCE IN 80 COL.
MODE ONLY -- IT BECOMES THE LOW BIT OF THE DOUBLED WORD.  sO, IF YOU WANT THE
RIGHT EDGE OF THE SCREEN, USE THE VALUE $c000+319.


sPRITES
-------
tHE c64 CONTAINS A CHIP TO HANDLE SPRITES IN HARDWARE. uNFORTUNATELY, THIS CHIP
IS NOT AVAILABLE ON THE 128, SO THE FUNCTIONS OF THAT CHIP HAVE BEEN SIMULATED
IN SOFTWARE THAT IS INCLUDED IN THE 128 KERNAL.  mOST OF THE CAPABILITIES OF
THE vic CHIP HAVE BEEN TAKEN CARE OF, AND IF YOU ARE NOT DOING EXOTIC THINGS
WITH SPRITES YOUR CODE MAY WORK WITH ONE OR TWO CHANGES.

tHE MAJOR CHANGES INCLUDE: SPRITE 0 (THE CURSOR) IS TREATED DIFFERENTLY THAN
ANY OTHER SPRITE.  tHE CODE FOR THIS BEAST HAS BEEN OPTIMIZED TO GET REASONABLY
FAST MOUSE RESPONSE, WITH A RESULTING LOSS IN FUNCTIONALITY.  yOU CANNOT DOUBLE
THE CURSOR'S SIZE IN EITHER X OR Y.  yOU CANNOT CHANGE THE COLOR OF THE CURSOR.
tHE SIZE OF THE CURSOR IS LIMITED TO 16-PIXELS WIDE AND 8 LINES HIGH.  oNE
ADDED FEATURE IS THE ABILITY TO ADD A WHITE OUTLINE TO THE PICTURE THAT IS USED
FOR THE CURSOR.  tHIS ALLOWS IT TO BE SEEN WHILE MOVING OVER A BLACK
BACKGROUND.

fOR THE OTHER 7 SPRITES, ALL THE CAPABILITIES HAVE BEEN EMULATED EXCEPT FOR
COLOR AND COLLISION DETECTION.  iN ADDITION, THE 64TH BYTE OF THE SPRITE
PICTURE DEFINITION (PREVIOUSLY UNUSED) IS NOW USED TO PROVIDE SOME SIZE INFO
ABOUT THE SPRITE.  tHIS IS USED TO OPTIMIZE THE DRAWING CODE. hERE ARE SOME
PROBLEM AREAS TO WATCH OUT FOR:

wRITING DIRECTLY TO THE SCREEN:

sINCE THE OLD SPRITE WERE HANDLED WITH HARDWARE, WRITING TO THE SCREEN WASN'T
A PROBLEM.  iF YOU DO IT (SYSTEM CALLS not INCLUDED), THEN CALL "tEMPhIDEmOUSE"
BEFORE THE WRITE.  tHIS WILL ERASE THE CURSOR AND ANY SPRITES YOU HAVE ENABLED.
yOU DON'T HAVE TO DO ANYTHING TO GET THEM BACK, THIS IS DONE AUTOMATICALLY
DURING THE NEXT MAIN LOOP.

aLL SPRITE PICTURE DATA:

aLL PICTURE DATA SHOULD BE ADJUSTED TO INCLUDE THE 64TH BYTE.  tHIS BYTE HAS
SIZE INFORMATION THAT IS READ BY THE SOFTWARE SPRITE ROUTINES, EVEN IF THEY
ARE GARBAGE VALUES.  tHE FORMAT OF THIS BYTE IS: HIGH BIT SET MEANS THAT THE
SPRITE IS NO MORE THAT 9 PIXELS WIDE (THIS MEANS IT CAN BE SHIFTED 7 TIMES
AND STILL BE CONTAINED IN 2 BYTES).  tHE REST OF THE BYTE IS A COUNT OF THE
SCAN LINES IN THE SPRITE.   yOU CAN EITHER INCLUDE THIS INFO AS PART OF THE
PICTURE DEFINITION, OR STUFF IT INTO THE RIGHT PLACE WITH SOME SPECIAL CODE.

wRITING DIRECTLY TO THE vic CHIP:

tHIS IS GENERALLY OK, SINCE THE SPRITE EMULATION ROUTINES TAKE THE POSITION
AND DOUBLING INFO FROM THE REGISTERS ON THE vic CHIP, WITH THE EXCEPTION OF THE
X POSITION.  tHE vic CHIP ALLOWS 9 BITS FOR X POSITIONS, WHICH IS NOT ENOUGH
 640-WIDE SCREEN.  yOU SHOULD WRITE THE X POSITION TO THE GLOBAL VARIABLES
"REQxPOS0, REQxPOS1..." (REQUEST X POS).  tHESE ARE FULL WORDS, IN CONSECUTIVE
LOCATIONS.  bETTER YET, USE THE "pOSsPRITE" CALL IN THE KERNEL.

rEADING VALUES FROM THE vic CHIP:

tHIS IS ALSO OK FOR THE STATUS VALUES AND FOR THE Y POSITION.  tHE X POSITION
CAN BE USEFUL ALSO, IF YOU USE THE pOSsPRITE CALL.  iN ADDITION TO FILLING
THE GLOBAL VARIABLES REQxPOS0, ETC., THIS CALL DIVIDES THE X POSITION BY TWO
AND STUFFS IT INTO THE vic CHIP.

uSING vic CHIP COLLISION DETECTION:

tHIS IS IFFY.  tHE CHIP CONTINUES TO OPERATE, SO IF YOU ARE USING THE
pOSsPRITE CALL (SEE ABOVE) COLLISIONS SHOULD BE DETECTED WITH SOME LOSS OF
ACCURACY (THE LOW BIT).  tHIS HAS NOT BEEN TESTED, SO IF YOU TRY IT -- REPORT
THE RESULTS HERE.

wRITING TO THE vic CHIP (OR CALLING pOSsPRITE, eNABLsPRITE, dISABLsPRITE)
AT INTERRUPT LEVEL:

dON'T DO IT.  sINCE THE MOUSE AND THE SPRITES ARE DRAWN AT MAIN LOOP, THIS
CAUSES SUBTLE, IRREPRODUCABLE TIMING BUGS THAT ARE IMPOSSIBLE TO GET OUT.

kNOWN BUGS IN RELEASE 1 OF geos 128
-----------------------------------

1) iF LOCATION $1300 IN APPLICATION SPACE IS ZERO, THEN SPRITES IN 80 COLUMN
MODE GO HAYWIRE.  aLL OF OUR CURRENT APPLICATIONS THAT RUN IN 80 COLUMN
MODE HAVE PUT IN A PATCH FOR THIS.  bUG IS IN SPRITE CODE.

2) dOUBLING BITMAPS THROUGH bITMAPcLIP DOESN'T WORK.

3) IbITMAPcLIP NEEDS CALL TO tEMPhIDEmOUSE BEFORE BEING CALLED.


;**************************************************************************
;tHIS FILE CONTAINS ADDITIONAL MEMORY MAP DEFINITIONS FOR APPLICATIONS WHICH
;WILL RUN UNDER THE geos 128 KERNAL. 12/11/87.
;**************************************************************************

;mEMORY-MANAGEMENT UNIT IN c-128

MMU= $d500
vdc= $d600

;aDDRESS OF MEMORY-MAP CONFIGURATION REGISTER IN c-128

CONFIG= $ff00

;mISC ADDRESSES:

KEYREG= $D02F;c-128 KEYBOARD REGISTER FOR # PAD & OTHER KEYS
CLKREG= $D030;c-128 CLOCK SPEED REGISTER

;aDDRESS OF INPUT DRIVER

mousebase= $fd00
endmouse= $fe80

;nOTE THAT THE JUMP TABLE ENTRIES FOR INPUT DRIVER ROUTINES HAVE NOT MOVED;
;tHEY ARE STILL AT mousejmp ($fe80). iN 128 geos, THERE IS ONE ADDITIONAL
;VECTOR:

sETmOUSE= mousejmp+9;($fe89)

;jUMP ADDRESSES WITHIN DISK DRIVERS -- THESE ARE ONLY VALID FOR NON-1541
;DISK DRIVE TYPES, AND FOR THE 128 VERSION OF THE 1541 DRIVER:

gET1STdIReNTRY= $9030;RETURNS FIRST DIR ENTRY
gETnXTdIReNTRY= $9033;RETURNS NEXT DIR ENTRY
aLLOCATEbLOCK= $9048;ALLOCATES SPECIFIC BLOCK
rEADlINK= $904b;LIKE rEADbLOCK, BUT RETURNS ONLY 1ST TWO BYTES

;tHE FOLLOWING ADDRESS HOLDS INFO ABOUT THE CURRENT 128 GRAPHICS MODE:
;$00 FOR vic, $80 FOR vdc 640*200, AND $c0 FOR vdc 640*400 (NOT YET SUPPORTED).

GRAPHICSmODE= $003F;HOLDS CURRENT 128 GRAPHICS MODE

;mISC VECTORS:

jMPiNDx= $9d80;ADDRESS OF ROUTINE USED BY 128 KERNAL

;-----------------------------------------------------------------------------
;tHIS IS A SECOND global MEMORY AREA FOR geos. iT IS HERE SO THAT THESE
;VARIABLES MAY BE IN THE SAME PLACE IN v1.3 AS THEY ARE RUNNING v1.2 WITH
;THE v1.3 DESKtOP. tHIS ALLOWS OTHER INPUT DRIVERS TO BE AUTO-BOOTED BY
;THOSE WHO HAVE A v1.2 geos kernal, BUT HAVE GOTTEN THE v1.3 DESKtOP VIA
;A DOWNLOAD OR UP-GRADE DISK. tHEY ARE equated TO BE PAST THE LOCAL geos
;VARIABLES, IN FACT AT THE END OF THE geos ram SPACE. hERE THEY MUST
;PERMANENTLY RESIDE, FOR THE SAKE OF COMPATIBILITY.


;sAVED VALUE OF MOBY2 FOR CONTEXT SAVING DONE IN DLG BOXES & DESK ACCESSORIES.
;lEFT OUT OF ORIGINAL geos SAVE CODE, PUT HERE SO WE DON'T SCREW UP DESK
;ACCESSORIES, ETC, THAT KNOW THE SIZE OF totsramsaved ABOVE.

SAVEDMOBY2= $88BB

;COPY OF REG 24 IN vdc FOR c128

SCREEN80POLARITY= $88BC

;sCREEN COLORS FOR 80 COLUMN MODE ON c128. cOPY OF REG 26 IN vdc

SCREEN80COLORS= $88BD

;hOLDS CURRENT COLOR MODE FOR c128 COLOR ROUTINES.

VDCcLRmODE= $88BE

;(4 BYTES) 1 BYTE EACH RESERVED FOR DISK DRIVERS ABOUT EACH DEVICE
;(EACH DRIVER MAY USE DIFFERENTLY)

DRIVEdATA= $88BF

;nUMBER OF 64k RAM BANKS AVAILABLE IN rAM eXPANSION uNIT. 0 IF NONE AVAILABLE.
RAMeXPsIZE= $88C3

;iF ram EXPANSION IS IN, bANK 0 IS RESERVED FOR THE KERNAL'S USE. tHIS BYTE
;CONTAINS FLAGS DESIGNATING ITS USAGE:
;
; bIT 7:  IF 1, $0000-$78ff USED BY mOVEdATA ROUTINE
; bIT 6:  IF 1, $8300-$b8ff HOLDS DISK DRIVERS FOR DRIVES a THROUGH c
; bIT 5:  IF 1, $7900-$7dff IS LOADED WITH geos RAM AREA $8400-$88ff BY tObASIC
;ROUTINE WHEN GOING TO basic
; bIT 4:  IF 1, $7e00-$82ff IS LOADED WITH REBOOT CODE BY A SETUP auto-exec
;FILE, WHICH IS LOADED BY THE RESTART CODE IN geos AT $c000 IF
;THIS FLAG IS SET, AT $6000, INSTEAD OF LOADING geosboot.
;aLSO, IN THE AREA $b900-$fc3f IS SAVED THE KERNAL FOR FAST
;RE-BOOT WITHOUT SYSTEM DISK (DEPENDING ON SETUP FILE).
;tHIS AREA SHOULD BE UPDATED WHEN INPUT DEVICES ARE CHANGED
;(IMPLEMENTED IN v1.3 DESKtOP)

SYSramfLG= $88C4

;tHIS FLAG IS CHANGED FROM 0 TO $ff AFTER DESKtOP COMES UP FOR THE FIRST TIME
;AFTER BOOTING.

FIRSTbOOT= $88C5

;(4 BYTES) cURRENT DISK TYPE FOR EACH DRIVE (COPIED FROM DISKtYPE)

CURtYPE= $88C6

;(4 BYTES) ram BANK FOR EACH DISK DRIVE TO USE IF DRIVE TYPE IS ram disk
;OR sHADOWED dRIVE

RAMbASE= $88C7

;(17 BYTES) hOLDS NAME OF CURRENT INPUT DEVICE

INPUTdEVnAME= $88CB

;(18 BYTES) dISK NAME OF DISK IN DRIVE c. (pADDED WITH $A0)
dRccURdKnM= $88DC

;(18 BYTES) dISK NAME OF DISK IN DRIVE d. (pADDED WITH $A0)
dRdcURdKnM= $88EE

;(256 BYTES) 2ND DIRECTORY HEADER BLOCK, FOR LARGER DISK CAPACITY DRIVES
;(SUCH AS 1571)
DIR2hEAD= $8900

;-----------------------------------------------------------------------------


;**************************************************************************
;tHIS FILE CONTAINS ADDITIONAL JUMP-TABLE ENTRIES FOR APPLICATIONS WHICH
;WILL RUN UNDER THE geos 128 KERNAL. 12/11/87.
;**************************************************************************

tEMPhIDEmOUSE= $C2D7
sETmOUSEpICTURE= $C2DA
sETnEWmODE= $C2DD
nORMALIZEx= $C2E0
mOVEbdATA= $C2E3
sWAPbdATA= $C2E6
vERIFYbdATA= $C2E9
dOboP= $C2EC
aCCESScACHE= $C2EF
hIDEoNLYmOUSE= $C2F2
sETcOLORmODE= $C2F5
cOLORcARD= $C2F8
cOLORrECTANGLE= $C2FB


;**************************************************************************
;tHIS FILE CONTAINS ADDITIONAL CONSTANT DEFINITIONS FOR APPLICATIONS WHICH
;WILL RUN UNDER THE geos 128 KERNAL. 12/11/87
;**************************************************************************

;tHE FOLLOWING EQUATES DEFINE THE NUMBERS WRITTEN TO THE "CONFIG"
;REGISTER (LOCATION $ff00 IN c-128). tHIS REGISTER CONTROLS THE MEMORY MAP
;OF THE c-128.
cioin= $7e;60k ram, 4k i/o SPACE IN
cram64k= $7f;64k ram
ckrnlbasioin= $40;KERNAL, i/o AND BASIC rom'S MAPPED INTO MEMORY
ckrnlioin= $4e;kERNAL rom AND i/o SPACE MAPPED IN

;kEYBOARD EQUATES
keyhelp= 25
keyalt= 26
keyesc= 27
keynoscrl= 7
keyenter= 11

;128 SCREEN SIZE CONSTANTS
screenbytewidth= 80
screenpixelwidth= 640

;nEW geos FILE TYPES:
input128= 15;128 iNPUT DRIVER

;nEW # OF FILE TYPES, INCLUDING nongeos (=0)
numfiletypes= 16

;tHE FOLLOWING EQUATE CAN BE USED AS AN OFFSET INTO A FILE'S HEADER BLOCK.
;iT POINTS TO THE BYTE WHICH CONTAINS FLAGS WHICH INDICATE IF THE PROGRAM
;WILL RUN UNDER c-128 geos IN 40 AND/OR 80 COLUMN MODES. tHESE FLAGS ARE VALID
;FOR APPLICATIONS, DESK ACCESSORIES, AND AUTO-EXEC FILES.
;
;b7 b6
; 0  0  RUNS UNDER 128 geos, BUT IN 40 COLUMN MODE ONLY
; 0  1  RUNS UNDER 128 geos IN 40 AND 80 COLUMN MODES
; 1  0  does not run UNDER 128 geos (DESKtOP WILL DISPLAY DIALOG BOX)
; 1  1  RUNS UNDER 128 geos IN 80 COLUMN MODE ONLY
off128flags= 96

;DISK EQUATES
dir1581track= 40;TRACK # RESERVED ON 1581 DISK FOR DIRECTORY
drv1581= 3;dRIVE TYPE cOMMODORE 1581
drvnetwork= 15;dRIVE TYPE FOR geos GEOnET "DRIVE"

;EQUATE FOR ERROR VALUE WHICH INDICATES AN ATTEMPT HAS BEEN MADE TO LOAD
;AN APPLICATION WHICH CANNOT BE RUN UNDER THE CURRENT c128 GRAPHICS MODE.
incompatible= 14